一、XDevice
设备对象类，SDK 中使用同时也提供给开发者使用的设备对象类。该类包括了设备的基本属性及部分相关方法。
- 以下方法说明中明确提供不推荐使用的方法，即为不建议开发者调用或者是开发者不应该进行任何数据修改。
- 以下文档中未提及的方法均属于不推荐使用的方法
1、Reference
以下为此类中关联的Class及相关说明
| 类名 | 类型 | 说明 |
|---|---|---|
| XDevice.State | 枚举类 | 设备状态，见下文 |
| XDevice.Event | 枚举类 | 设备事件，见下文 |
2、Field
以下为此类中的常用字段及说明。
2.1、Attributes
由于设备对象包含的属性较多，不一一罗列其属性的getter/setter方法，以下字段都支持对应的方法，方法列表中不再赘述。大部分情况下，以下属性为仅读属性
| 字段名 | 字段类型 | getter支持返回null | 说明 |
|---|---|---|---|
| macAddress | String | 否 | 设备 mac 地址 |
| productId | String | 否 | 设备产品ID |
| deviceTag | String | 否 | 设备标识 |
| protocolVersion | byte | - | 设备版本号，注意该值不一定有效，可能为0 |
| bound | boolean | - | 设备是否已与 APP 建立连接配对过 |
| deviceId | int | - | 设备ID |
| deviceName | String | 是 | 设备名称，该值为保存到云端的数据，可能为 null |
| active | boolean | - | 设备是否已经激活 |
| isDeviceConnectedCloud | boolean | - | 设备是否已经连接到云端服务器 |
| lastLogin | String | 是 | 设备最后一次登录日期，2018-06-01T19:45:28.417Z |
| activeDate | String | 是 | 设备激活日期，2018-05-29T11:19:40.752Z |
| activeCode | String | 是 | 激活码 |
| authorizeCode | String | 是 | 认证码 |
| mcuMod | String | 是 | mcu 型号 |
| mcuVersion | String | 是 | mcu 版本号 |
| firmwareMod | String | 是 | 固件型号 |
| firmwareVersion | String | 是 | 固件版本号 |
| role | int | - | 用户与设备的订阅关系，见下文 |
| authority | String | 否 | 设备访问权限，见下文 |
| SN | String | 是 | 设备序列号 |
| subscriptionSource | int | - | 设备订阅来源，见下文 |
| subscriptionDate | String | 是 | 设备订阅日期，2018-06-01T19:45:28.417Z |
| softInitDate | String | 是 | 设备销售日期，2018-06-01T19:45:28.417Z |
2.2、Role
用户与设备的订阅关系
| 字段名 | 字段类型 | 值 | 说明 |
|---|---|---|---|
| ADMIN | int | 0 | 用户为设备管理员 |
| USER | int | 1 | 用户为普通设备使用者 |
2.3、Authority
设备的控制权限或访问权限
| 字段名 | 字段类型 | 值 | 说明 |
|---|---|---|---|
| R | String | R | 可读 |
| W | String | W | 可写 |
| RW | String | RW | 可读写 |
2.4、SubscriptionSource
产生订阅关系的来源
| 字段名 | 字段类型 | 值 | 说明 |
|---|---|---|---|
| UNKNOWN | int | 0 | 未知来源 |
| OUTER_NET_SCAN | int | 1 | 外网扫描 |
| USER_SHARE | int | 2 | 其他用户分享 |
| QR_CODE | int | 3 | 二维码订阅 |
| HOME_FAMILY | int | 4 | Home家庭 |
| MANUALLY_ADD | int | 5 | 用户手动添加设备 |
| WECHAT_PUBLIC | int | 6 | 微信公众号同步 |
3、Methods
以下方法为开发过程常用的方法说明，参数说明及返回值说明。此处仅提供了推荐开发者使用及可能需要使用的方法，部分未列出方法请根据实际情况评估调用。
3.1、construtor
public XDevice()- 方法说明：
默认无参构造方法，通过此方法创建的设备对象不存在 mac 与 pid
public XDevice(@NotNull String json) throws IllegalArgumentException- 方法说明：
通过 json 字符串反序列化创建设备对象，此方法用于将序列化为 json 字符串后的设备对象还原。注意还原的设备对象必然是丢失了一部分数据或者是存在部分数据状态不准确的情况（在序列化与反序列化时间间隔足够长的情况下），通常仅用于持久化或者传输设备对象。
- 参数说明：
| 参数名 | 类型 | 说明 |
|---|---|---|
| json | String | 设备序列化的 json 字符串，不允许为 null |
| exception | IllegalArgumentException | 当反序列化失败时，抛出异常信息 |
3.2、toJson
@NotNull
public String toJson()- 方法说明：
将设备对象序列化成 json 字符串
- 返回值：String，json 字符串；返回设备的序列化 json 字符串，不为 null
4、Relevant Class
以下为此类中的关联类或内部类，包括了设备状态与设备事件枚举类
4.1、XDevice.State
| 字段名 | 说明 |
|---|---|
| DETACHED | XDevice的状态未知 |
| DISCONNECTED | SDK设备与设备失去连接 |
| CONNECTING | SDK正在连接设备 |
| CONNECTED | SDK设备保持连接 |
当前当设备状态未知或设备不存在时，默认都返回 DISCONNECTED
4.2、XDevice.Event
| 字段名 | 说明 |
|---|---|
| 字段名 | 说明 |
| SUBSCRIBE | 订阅关系建立 |
| UNSUBSCRIBE | 订阅关系解除 |
| INFO | 设备基本属性变化 |
| PROPERTY | 设备扩展属性变化 |
设备事件在全局的设备监听回调中，设备变更时会有相应的事件，请参考参考设备管理对象关联接口 XLinkDeviceStateListener.onDeviceChanged
5、Addendum
设备对象的 json 序列化结构：
{
"subscribe_date": "2018-06-01T19:45:28.417Z",
"is_active": true,
"role": "0",
"last_login": "2018-06-04T20:49:37.78Z",
"firmware_mod": "1",
"active_code": "XXX",
"active_date": "2018-05-29T11:19:40.752Z",
"is_online": false,
"mcu_version": "1",
"firmware_version": "3",
"source": "1",
"pairing_id": "XXX",
"mac": "ABC001",
"soft_init_date": "",
"pairing_key": "xxx",
"mcu_mod": "1",
"product_id": "xxx",
"authority": "RW",
"name": "",
"authorize_code": "xxx",
"id": "xxx",
"sn": ""
}二、更新日志
| 日期 | 更新内容 |
|---|---|
| 2019-01-15 | 自v6.2.6.x版本起，新增设备与云端服务器连接状态字段 |
| 2018-08-22 | 初稿，自 X-MQTT SDK v6.2版本起 |
